home *** CD-ROM | disk | FTP | other *** search
/ Visual Cafe 3 / Visual Cafe 3.ISO / Vcafe / Main.bin / PropertyEditor.java < prev    next >
Text File  |  1998-09-22  |  7KB  |  186 lines
  1. /*
  2.  * @(#)PropertyEditor.java    1.27 98/07/01
  3.  *
  4.  * Copyright 1996-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  * 
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.beans;
  16.  
  17. /**
  18.  * A PropertyEditor class provides support for GUIs that want to
  19.  * allow users to edit a property value of a given type.
  20.  * <p>
  21.  * PropertyEditor supports a variety of different kinds of ways of
  22.  * displaying and updating property values.  Most PropertyEditors will
  23.  * only need to support a subset of the different options available in
  24.  * this API.
  25.  * <P>
  26.  * Simple PropertyEditors may only support the getAsText and setAsText
  27.  * methods and need not support (say) paintValue or getCustomEditor.  More
  28.  * complex types may be unable to support getAsText and setAsText but will
  29.  * instead support paintValue and getCustomEditor.
  30.  * <p>
  31.  * Every propertyEditor must support one or more of the three simple
  32.  * display styles.  Thus it can either (1) support isPaintable or (2)
  33.  * both return a non-null String[] from getTags() and return a non-null
  34.  * value from getAsText or (3) simply return a non-null String from 
  35.  * getAsText().
  36.  * <p>
  37.  * Every property editor must support a call on setValue when the argument
  38.  * object is of the type for which this is the corresponding propertyEditor.
  39.  * In addition, each property editor must either support a custom editor,
  40.  * or support setAsText.
  41.  * <p>
  42.  * Each PropertyEditor should have a null constructor.
  43.  */
  44.  
  45. public interface PropertyEditor {
  46.  
  47.     /**
  48.      * Set (or change) the object that is to be edited.  Builtin types such
  49.      * as "int" must be wrapped as the corresponding object type such as
  50.      * "java.lang.Integer".
  51.      *
  52.      * @param value The new target object to be edited.  Note that this
  53.      *     object should not be modified by the PropertyEditor, rather 
  54.      *     the PropertyEditor should create a new object to hold any
  55.      *     modified value.
  56.      */
  57.     void setValue(Object value);
  58.  
  59.     /**
  60.      * @return The value of the property.  Builtin types such as "int" will
  61.      * be wrapped as the corresponding object type such as "java.lang.Integer".
  62.      */
  63.  
  64.     Object getValue();
  65.  
  66.     //----------------------------------------------------------------------
  67.  
  68.     /**
  69.      * @return  True if the class will honor the paintValue method.
  70.      */
  71.  
  72.     boolean isPaintable();
  73.  
  74.     /**
  75.      * Paint a representation of the value into a given area of screen
  76.      * real estate.  Note that the propertyEditor is responsible for doing
  77.      * its own clipping so that it fits into the given rectangle.
  78.      * <p>
  79.      * If the PropertyEditor doesn't honor paint requests (see isPaintable)
  80.      * this method should be a silent noop.
  81.      * <p>
  82.      * The given Graphics object will have the default font, color, etc of
  83.      * the parent container.  The PropertyEditor may change graphics attributes
  84.      * such as font and color and doesn't need to restore the old values.
  85.      *
  86.      * @param gfx  Graphics object to paint into.
  87.      * @param box  Rectangle within graphics object into which we should paint.
  88.      */
  89.     void paintValue(java.awt.Graphics gfx, java.awt.Rectangle box);
  90.  
  91.     //----------------------------------------------------------------------
  92.  
  93.     /**
  94.      * This method is intended for use when generating Java code to set
  95.      * the value of the property.  It should return a fragment of Java code
  96.      * that can be used to initialize a variable with the current property
  97.      * value.
  98.      * <p>
  99.      * Example results are "2", "new Color(127,127,34)", "Color.orange", etc.
  100.      *
  101.      * @return A fragment of Java code representing an initializer for the
  102.      *       current value.
  103.      */
  104.     String getJavaInitializationString();
  105.  
  106.     //----------------------------------------------------------------------
  107.  
  108.     /**
  109.      * @return The property value as a human editable string.
  110.      * <p>   Returns null if the value can't be expressed as an editable string.
  111.      * <p>   If a non-null value is returned, then the PropertyEditor should
  112.      *         be prepared to parse that string back in setAsText().
  113.      */
  114.     String getAsText();
  115.  
  116.     /**
  117.      * Set the property value by parsing a given String.  May raise
  118.      * java.lang.IllegalArgumentException if either the String is
  119.      * badly formatted or if this kind of property can't be expressed
  120.      * as text.
  121.      * @param text  The string to be parsed.
  122.      */
  123.     void setAsText(String text) throws java.lang.IllegalArgumentException;
  124.  
  125.     //----------------------------------------------------------------------
  126.  
  127.     /**
  128.      * If the property value must be one of a set of known tagged values, 
  129.      * then this method should return an array of the tags.  This can
  130.      * be used to represent (for example) enum values.  If a PropertyEditor
  131.      * supports tags, then it should support the use of setAsText with
  132.      * a tag value as a way of setting the value and the use of getAsText
  133.      * to identify the current value.
  134.      *
  135.      * @return The tag values for this property.  May be null if this 
  136.      *   property cannot be represented as a tagged value.
  137.      *    
  138.      */
  139.     String[] getTags();
  140.  
  141.     //----------------------------------------------------------------------
  142.  
  143.     /**
  144.      * A PropertyEditor may choose to make available a full custom Component
  145.      * that edits its property value.  It is the responsibility of the
  146.      * PropertyEditor to hook itself up to its editor Component itself and
  147.      * to report property value changes by firing a PropertyChange event.
  148.      * <P>
  149.      * The higher-level code that calls getCustomEditor may either embed
  150.      * the Component in some larger property sheet, or it may put it in
  151.      * its own individual dialog, or ...
  152.      *
  153.      * @return A java.awt.Component that will allow a human to directly
  154.      *      edit the current property value.  May be null if this is
  155.      *        not supported.
  156.      */
  157.  
  158.     java.awt.Component getCustomEditor();
  159.  
  160.     /**
  161.      * @return  True if the propertyEditor can provide a custom editor.
  162.      */
  163.     boolean supportsCustomEditor();
  164.   
  165.     //----------------------------------------------------------------------
  166.  
  167.     /**
  168.      * Register a listener for the PropertyChange event.  When a
  169.      * PropertyEditor changes its value it should fire a PropertyChange
  170.      * event on all registered PropertyChangeListeners, specifying the
  171.      * null value for the property name and itself as the source.
  172.      *
  173.      * @param listener  An object to be invoked when a PropertyChange
  174.      *        event is fired.
  175.      */
  176.     void addPropertyChangeListener(PropertyChangeListener listener);
  177.  
  178.     /**
  179.      * Remove a listener for the PropertyChange event.
  180.      *
  181.      * @param listener  The PropertyChange listener to be removed.
  182.      */
  183.     void removePropertyChangeListener(PropertyChangeListener listener);
  184.  
  185. }
  186.